Liftoff is a lightweight CLI framework that helps you build command-line tools. It provides a way to bootstrap your CLI application with support for configuration files, environment variables, and plugins.
Command-line Interface Bootstrapping
This feature allows you to bootstrap a CLI application with Liftoff. The code sample demonstrates how to create a new Liftoff instance and launch it, printing the environment information.
const Liftoff = require('liftoff');
const MyApp = new Liftoff({
name: 'myapp',
moduleName: 'myapp',
configName: 'myappfile',
extensions: {
'.js': null
}
});
MyApp.launch({}, (env) => {
console.log('MyApp is running!');
console.log('Environment:', env);
});Configuration File Support
Liftoff supports loading configuration files. The code sample shows how to load a configuration file if it exists and print its contents.
const Liftoff = require('liftoff');
const MyApp = new Liftoff({
name: 'myapp',
configName: 'myappfile',
extensions: {
'.js': null
}
});
MyApp.launch({}, (env) => {
if (env.configPath) {
const config = require(env.configPath);
console.log('Loaded config:', config);
} else {
console.log('No config file found.');
}
});Environment Variable Support
Liftoff can access and utilize environment variables. The code sample demonstrates how to print all environment variables when the CLI application is launched.
const Liftoff = require('liftoff');
const MyApp = new Liftoff({
name: 'myapp',
configName: 'myappfile',
extensions: {
'.js': null
}
});
MyApp.launch({}, (env) => {
console.log('Environment Variables:', process.env);
});Commander is a popular package for building command-line interfaces. It provides a simple and flexible way to define commands, options, and arguments. Compared to Liftoff, Commander focuses more on command parsing and less on configuration and environment management.
Yargs is another powerful library for building CLI applications. It offers extensive features for parsing arguments, generating help messages, and handling commands. Yargs provides more built-in utilities for argument parsing compared to Liftoff, which focuses on bootstrapping and configuration.
Oclif is a framework for building command-line tools, developed by Heroku. It provides a robust structure for creating complex CLI applications with plugins and command management. Oclif is more opinionated and feature-rich compared to Liftoff, which is more lightweight and flexible.
Launch your command line tool with ease.
See this blog post, check out this proof of concept, or read on.
Say you're writing a CLI tool. Let's call it hacker. You want to configure it using a Hackerfile. This is node, so you install hacker locally for each project you use it in. But, in order to get the hacker command in your PATH, you also install it globally.
Now, when you run hacker, you want to configure what it does using the Hackerfile in your current directory, and you want it to execute using the local installation of your tool. Also, it'd be nice if the hacker command was smart enough to traverse up your folders until it finds a Hackerfile—for those times when you're not in the root directory of your project. Heck, you might even want to launch hacker from a folder outside of your project by manually specifying a working directory. Liftoff manages this for you.
So, everything is working great. Now you can find your local hacker and Hackerfile with ease. Unfortunately, it turns out you've authored your Hackerfile in coffee-script, or some other JS variant. In order to support that, you have to load the compiler for it, and then register the extension for it with node. Good news, Liftoff can do that, and a whole lot more, too.
Create an instance of Liftoff to invoke your application.
An example utilizing all options:
const Hacker = new Liftoff({
name: 'hacker',
processTitle: 'hacker',
moduleName: 'hacker',
configName: 'hackerfile',
extensions: {
'.js': null,
'.json': null,
'.coffee': 'coffee-script/register'
},
v8flags: ['--harmony'] // or v8flags: require('v8flags')
});
Sugar for setting processTitle, moduleName, configName automatically.
Type: String
Default: null
These are equivalent:
const Hacker = Liftoff({
processTitle: 'hacker',
moduleName: 'hacker',
configName: 'hackerfile'
});
const Hacker = Liftoff({name:'hacker'});
Sets which module your application expects to find locally when being run.
Type: String
Default: null
Sets the name of the configuration file Liftoff will attempt to find. Case-insensitive.
Type: String
Default: null
Set extensions to include when searching for a configuration file. If an external module is needed to load a given extension (e.g. .coffee), the module name should be specified as the value for the key.
Type: Object
Default: {".js":null,".json":null}
Examples:
In this example Liftoff will look for myappfile{.js,.json,.coffee}. If a config with the extension .coffee is found, Liftoff will try to require coffee-script/require from the current working directory.
const MyApp = new Liftoff({
name: 'myapp',
extensions: {
'.js': null,
'.json': null,
'.coffee': 'coffee-script/register'
}
});
In this example, Liftoff will look for .myapp{rc}.
const MyApp = new Liftoff({
name: 'myapp',
configName: '.myapp',
extensions: {
'rc': null
}
});
In this example, Liftoff will automatically attempt to load the correct module for any javascript variant supported by interpret (as long as it does not require a register method).
const MyApp = new Liftoff({
name: 'myapp',
extensions: require('interpret').jsVariants
});
Any flag specified here will be applied to node, not your program. Useful for supporting invocations like myapp --harmony command, where --harmony should be passed to node, not your program. This functionality is implemented using flagged-respawn. To support all v8flags, see v8flags.
Type: Array|Function
Default: null
If this method is a function, it should take a node-style callback that yields an array of flags.
Sets what the process title will be.
Type: String
Default: null
A method to handle bash/zsh/whatever completions.
Type: Function
Default: null
An object of configuration files to find. Each property is keyed by the default basename of the file being found, and the value is an object of path arguments keyed by unique names.
Note: This option is useful if, for example, you want to support an .apprc file in addition to an appfile.js. If you only need a single configuration file, you probably don't need this. In addition to letting you find multiple files, this option allows more fine-grained control over how configuration files are located.
Type: Object
Default: null
The fined module accepts a string representing the path to search or an object with the following keys:
path (required)
The path to search. Using only a string expands to this property.
Type: String
Default: null
name
The basename of the file to find. Extensions are appended during lookup.
Type: String
Default: Top-level key in configFiles
extensions
The extensions to append to name during lookup. See also: opts.extensions.
Type: String|Array|Object
Default: The value of opts.extensions
cwd
The base directory of path (if relative).
Type: String
Default: The value of opts.cwd
findUp
Whether the path should be traversed up to find the file.
Type: Boolean
Default: false
Examples:
In this example Liftoff will look for the .hacker.js file relative to the cwd as declared in configFiles.
const MyApp = new Liftoff({
name: 'hacker',
configFiles: {
'.hacker': {
cwd: '.'
}
}
});
In this example, Liftoff will look for .hackerrc in the home directory.
const MyApp = new Liftoff({
name: 'hacker',
configFiles: {
'.hacker': {
home: {
path: '~',
extensions: {
'rc': null
}
}
}
}
});
In this example, Liftoff will look in the cwd and then lookup the tree for the .hacker.js file.
const MyApp = new Liftoff({
name: 'hacker',
configFiles: {
'.hacker': {
up: {
path: '.',
findUp: true
}
}
}
});
In this example, the name is overridden and the key is ignored so Liftoff looks for .override.js.
const MyApp = new Liftoff({
name: 'hacker',
configFiles: {
hacker: {
override: {
path: '.',
name: '.override'
}
}
}
});
In this example, Liftoff will use the home directory as the cwd and looks for ~/.hacker.js.
const MyApp = new Liftoff({
name: 'hacker',
configFiles: {
'.hacker': {
home: {
path: '.',
cwd: '~'
}
}
}
});
Prepares the environment for your application with provided options, and invokes your callback with the calculated environment as the first argument. The environment can be modified before using it as the first argument to execute.
Example Configuration w/ Options Parsing:
const Liftoff = require('liftoff');
const MyApp = new Liftoff({name:'myapp'});
const argv = require('minimist')(process.argv.slice(2));
const onExecute = function (env, argv) {
// Do post-execute things
};
const onPrepare = function (env) {
console.log('my environment is:', env);
console.log('my liftoff config is:', this);
MyApp.execute(env, onExecute);
};
MyApp.prepare({
cwd: argv.cwd,
configPath: argv.myappfile,
require: argv.require,
completion: argv.completion
}, onPrepare);
Example w/ modified environment
const Liftoff = require('liftoff');
const Hacker = new Liftoff({
name: 'hacker',
configFiles: {
'.hacker': {
home: { path: '.', cwd: '~' }
}
}
});
const onExecute = function (env, argv) {
// Do post-execute things
};
const onPrepare = function (env) {
env.configProps = ['home', 'cwd'].map(function(dirname) {
return env.configFiles['.hacker'][dirname]
}).filter(function(filePath) {
return Boolean(filePath);
}).reduce(function(config, filePath) {
return mergeDeep(config, require(filePath));
}, {});
if (env.configProps.hackerfile) {
env.configPath = path.resolve(env.configProps.hackerfile);
env.configBase = path.dirname(env.configPath);
}
Hacker.execute(env, onExecute);
};
Hacker.prepare({}, onPrepare);
Change the current working directory for this launch. Relative paths are calculated against process.cwd().
Type: String
Default: process.cwd()
Example Configuration:
const argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
cwd: argv.cwd
}, invoke);
Matching CLI Invocation:
myapp --cwd ../
Don't search for a config, use the one provided. Note: Liftoff will assume the current working directory is the directory containing the config file unless an alternate location is explicitly specified using cwd.
Type: String
Default: null
Example Configuration:
var argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
configPath: argv.myappfile
}, invoke);
Matching CLI Invocation:
myapp --myappfile /var/www/project/Myappfile.js
Examples using cwd and configPath together:
These are functionally identical:
myapp --myappfile /var/www/project/Myappfile.js
myapp --cwd /var/www/project
These can run myapp from a shared directory as though it were located in another project:
myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project1
myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project2
A string or array of modules to attempt requiring from the local working directory before invoking the launch callback.
Type: String|Array
Default: null
Example Configuration:
var argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
require: argv.require
}, invoke);
Matching CLI Invocation:
myapp --require coffee-script/register
A function called after your environment is prepared. A good place to modify the environment before calling execute. When invoked, this will be your instance of Liftoff. The env param will contain the following keys:
cwd: the current working directoryrequire: an array of modules that liftoff tried to pre-loadconfigNameSearch: the config files searched forconfigPath: the full path to your configuration file (if found)configBase: the base directory of your configuration file (if found)modulePath: the full path to the local module your project relies on (if found)modulePackage: the contents of the local module's package.json (if found)configFiles: an object of filepaths for each found config file (filepath values will be null if not found)A function to start your application, based on the env given. Optionally takes an array of forcedFlags, which will force a respawn with those node or V8 flags during startup. Invokes your callback with the environment and command-line arguments (minus node & v8 flags) after the application has been executed.
Example:
const Liftoff = require('liftoff');
const MyApp = new Liftoff({name:'myapp'});
const onExecute = function (env, argv) {
// Do post-execute things
console.log('my environment is:', env);
console.log('my cli options are:', argv);
console.log('my liftoff config is:', this);
};
const onPrepare = function (env) {
var forcedFlags = ['--trace-deprecation'];
MyApp.execute(env, forcedFlags, onExecute);
};
MyApp.prepare({}, onPrepare);
A function called after your application is executed. When invoked, this will be your instance of Liftoff, argv will be all command-line arguments (minus node & v8 flags), and env will contain the following keys:
cwd: the current working directoryrequire: an array of modules that liftoff tried to pre-loadconfigNameSearch: the config files searched forconfigPath: the full path to your configuration file (if found)configBase: the base directory of your configuration file (if found)modulePath: the full path to the local module your project relies on (if found)modulePackage: the contents of the local module's package.json (if found)configFiles: an object of filepaths for each found config file (filepath values will be null if not found)Deprecated: Please use prepare followed by execute. That's all this module does internally but those give you more control.
Launches your application with provided options, builds an environment, and invokes your callback, passing the calculated environment and command-line arguments (minus node & v8 flags) as the arguments.
Accepts any options that prepare allows, plus opt.forcedFlags.
Deprecated: If using prepare/execute, pass forcedFlags as the 2nd argument instead of using this option.
Allows you to force node or V8 flags during the launch. This is useful if you need to make sure certain flags will always be enabled or if you need to enable flags that don't show up in opts.v8flags (as these flags aren't validated against opts.v8flags).
If this is specified as a function, it will receive the built env as its only argument and must return a string or array of flags to force.
Type: String|Array|Function
Default: null
Example Configuration:
MyApp.launch({
forcedFlags: ['--trace-deprecation']
}, invoke);
Matching CLI Invocation:
myapp --trace-deprecation
Emitted when a module is pre-loaded.
var Hacker = new Liftoff({name:'hacker'});
Hacker.on('require', function (name, module) {
console.log('Requiring external module: '+name+'...');
// automatically register coffee-script extensions
if (name === 'coffee-script') {
module.register();
}
});
Emitted when a requested module cannot be preloaded.
var Hacker = new Liftoff({name:'hacker'});
Hacker.on('requireFail', function (name, err) {
console.log('Unable to load:', name, err);
});
Emitted when Liftoff re-spawns your process (when a v8flags is detected).
var Hacker = new Liftoff({
name: 'hacker',
v8flags: ['--harmony']
});
Hacker.on('respawn', function (flags, child) {
console.log('Detected node flags:', flags);
console.log('Respawned to PID:', child.pid);
});
Event will be triggered for this command:
hacker --harmony commmand
Check out how gulp uses Liftoff.
For a bare-bones example, try the hacker project.
To try the example, do the following:
hacker with npm install -g hacker.Hackerfile.js with some arbitrary javascript it.npm install hacker.hacker while in the same parent folder.4.0.0 (2021-11-22)
extends syntax in config files (#103)env.completion inside execute to allow additional configuration (#106)opts.require to opts.preloadopts.require to opts.preload (596926a)extends syntax in config files (#103) (68c9db7)env.completion inside execute to allow additional configuration (#106) (2a1fc4b)FAQs
Launch your command line tool with ease.
The npm package liftoff receives a total of 2,525,064 weekly downloads. As such, liftoff popularity was classified as popular.
We found that liftoff demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.